home *** CD-ROM | disk | FTP | other *** search
/ Software Vault: The Gold Collection / Software Vault - The Gold Collection (American Databankers) (1993).ISO / cdr49 / pgp23src.zip / PGFORMAT.DOC < prev    next >
Text File  |  1993-06-15  |  35KB  |  789 lines
  1. Internal Data Structures Used by PGP 2.3 (14 Jun 93)
  2. ==========================================================
  3.  
  4. This appendix describes the file formats used externally by Pretty
  5. Good Privacy (PGP), the RSA public key cryptography application.  The
  6. intended audience includes software engineers trying to port PGP to
  7. other hardware environments or trying to implement other PGP-
  8. compatible cryptography products, or anyone else who is curious.
  9.  
  10. [To be included: a description of ASCII armor.  And ASCII armored
  11. file is just like a binary file described here, but with an extra
  12. layer of encoding added, framing lines, and a checksum at the end.]
  13.  
  14.  
  15. Byte Order
  16. ----------
  17.  
  18. All integer data used by PGP is externally stored most significant
  19. byte (MSB) first, regardless of the byte order used internally by the
  20. host CPU architecture.  This is for cross-compatibility of messages
  21. and keys between hosts.  This covers multiprecision RSA integers, bit
  22. count prefix fields, byte count prefix fields, checksums, key IDs, and
  23. timestamps.
  24.  
  25. The MSB-first byte order for external packet representation was
  26. chosen only because many other crypto standards use it.
  27.  
  28.  
  29. Multiprecision Integers
  30. -----------------------
  31.  
  32. RSA arithmetic involves a lot of multiprecision integers, often
  33. having hundreds of bits of precision.  PGP externally stores a
  34. multiprecision integer (MPI) with a 16-bit prefix that gives the
  35. number of significant bits in the integer that follows.  The integer
  36. that follows this bitcount field is stored in the usual byte order, 
  37. with the MSB padded with zero bits if the bitcount is not a multiple
  38. of 8.  The bitcount always specifies the exact number of significant
  39. bits.  For example, the integer value 5 would be stored as these
  40. three bytes:
  41.  
  42.     00 03 05
  43.  
  44. An MPI with a value of zero is simply stored with the 16-bit bitcount 
  45. prefix field containing a 0, with no value bytes following it.
  46.  
  47.  
  48.  
  49. Key ID
  50. ------
  51.  
  52. Some packets use a "key ID" field.  The key ID is the least
  53. significant 64 bits of the RSA public modulus that was involved in
  54. creating the packet.  For all practical purposes it unique to each 
  55. RSA public key.
  56.  
  57.  
  58. User ID
  59. -------
  60.  
  61. Some packets contain a "user ID", which is an ASCII string that
  62. contains the user's name.  Unlike a C string, the user ID has a
  63. length byte at the beginning that has a byte count of the rest of the
  64. string.  This length byte does not include itself in the count.
  65.  
  66.  
  67. Timestamp
  68. ---------
  69.  
  70. Some packets contain a timestamp, which is a 32-bit unsigned integer
  71. of the number of seconds elapsed since 1970 Jan 1 00:00:00 GMT.  This
  72. is the standard format used by Unix timestamps.  It spans 136 years. 
  73.  
  74.  
  75.  
  76. Cipher Type Byte (CTB)
  77. ----------------------
  78.  
  79. Many of these data structures begin with a Cipher Type Byte (CTB),
  80. which specifies the type of data structure that follows it.  The CTB 
  81. bit fields have the following meaning (bit 0 is the LSB, bit 7 is the
  82. MSB):
  83.  
  84. Bit 7:     Always 1, which designates this as a CTB
  85. Bit 6:     Reserved.
  86. Bits 5-2:  CTB type field, specifies type of packet that follows
  87.            0001 - public-key-encrypted packet
  88.            0010 - secret-key-encrypted (signature) packet
  89.            0101 - Secret key certificate
  90.            0110 - Public key certificate
  91.            1000 - Compressed data packet
  92.            1001 - Conventional-Key-Encrypted data
  93.            1011 - Raw literal plaintext data, with filename and mode
  94.            1100 - Keyring trust packet
  95.            1101 - User ID packet, associated with public or secret key
  96.            1110 - Comment packet
  97.            Other CTB packet types are unimplemented.
  98. Bits 1-0:  Length-of-length field:
  99.            00 - 1 byte packet length field follows CTB
  100.            01 - 2 byte packet length field follows CTB
  101.            10 - 4 byte packet length field follows CTB
  102.            11 - no length field follows CTB, unknown packet length.
  103.            The 8-, 16-, or 32-bit packet length field after the CTB 
  104.            gives the length in bytes of the rest of the packet, not
  105.            counting the CTB and the packet length field.
  106.  
  107.  
  108.  
  109. RSA public-key-encrypted packet
  110. -------------------------------
  111.  
  112. Offset  Length  Meaning
  113. 0       1       CTB for RSA public-key-encrypted packet
  114. 1       2       16-bit (or maybe 8-bit) length of packet
  115. 3    1    Version byte (=2).  May affect rest of fields that follow.
  116. 4       8       64-bit Key ID
  117. 12    1    Algorithm byte for RSA (=1 for RSA).  
  118.         --Algorithm byte affects field definitions that follow.
  119. 13      ?       RSA-encrypted integer, encrypted conventional key
  120.                 packet.  (MPI with bitcount prefix)
  121.  
  122. The conventionally-encrypted ciphertext packet begins right after the 
  123. RSA public-key-encrypted packet that contains the conventional key.
  124.  
  125.  
  126.  
  127. Signature packet
  128. ----------------
  129.  
  130. Offset  Length  Meaning
  131. 0       1       CTB for secret-key-encrypted (signed) packet
  132. 1       2       16-bit (or maybe 8-bit) length of packet
  133. 3    1    Version byte (=2).  May affect rest of fields that follow.
  134.  
  135. 4    1    Length of following material that is implicitly included 
  136.         in MD calculation.
  137. 5    1    Signature classification field (see below). 
  138.         Implicitly append this to message for MD calculation.
  139. 6    4    32-bit timestamp of when signature was made.  
  140.         Implicitly append this to message for MD calculation.
  141. 10      2       Validity period, in number of DAYS (0 means forever)
  142.         Implicitly append this to message for MD calculation.
  143.  
  144. 12      8       64-bit Key ID
  145. 20    1    Algorithm byte for public key scheme (RSA=0x01).  
  146.         --Algorithm byte affects field definitions that follow.
  147. 21    1    Algorithm byte for message digest (MD5=0x01).
  148. 22    2    First 2 bytes of the Message Digest inside the 
  149.         RSA-encrypted integer, to help us figure out if we 
  150.         used the right RSA key to check the signature.
  151. 24      ?       RSA-encrypted integer, encrypted message digest
  152.                 (MPI with bitcount prefix).
  153.  
  154. If the plaintext that was signed is included in the same file as the
  155. signature packet, it begins right after the RSA secret-key-signed 
  156. packet that contains the message digest.  The plaintext has a
  157. "literal" CTB prefix.
  158.  
  159. The validity period field is generally only used for certifying keys. 
  160. It should be set to 0 otherwise, for regular message signatures.  It
  161. may be useful for PEM-like capabilities in future versions of PGP. 
  162. PGP 2.3 will always just set it to 0, and will ignore it.
  163.  
  164. There is a length field that specifies how many bytes of material is
  165. implicitly included in the MD calculation.  If this length field is
  166. 5, it means the following 1-byte classification field and the 4-byte
  167. timestamp are included in the signature packet.  If the length byte
  168. is 7, it means the 2-byte validity period is also included.  In PGP
  169. 2.3, we are using a length field of 5 for the material to be included
  170. in the MD calculation, so the validity period is unused and
  171. unincluded, and is assumed to be zeroed.  This makes the whole
  172. signature certificate shorter.
  173.  
  174. The signature classification field describes what kind of 
  175. signature certificate this is.  There are various hex values:
  176.     00 -    Signature of a message or document, binary image.  
  177.     01 -    Signature of a message or document, canonical text.  
  178.     10 -    Key certification, generic.  Only version of key
  179.         certification supported by PGP 2.0.
  180.         Material signed is public key pkt and User ID pkt.
  181.     11 -    Key certification, persona.  No attempt made at all 
  182.         to identify the user with a real name.
  183.         Material signed is public key pkt and User ID pkt.
  184.     12 -    Key certification, casual identification.  Some
  185.         casual attempt made to identify user with his name.
  186.         Material signed is public key pkt and User ID pkt.
  187.     13 -    Key certification, positive ID.  Heavy-duty
  188.         identification efforts, photo ID, direct contact 
  189.         with personal friend, etc.
  190.         Material signed is public key pkt and User ID pkt.
  191.     20 -     Key compromise.  User signs his own compromise
  192.         certificate.  Independent of user ID associations.
  193.         Material signed is public key pkt ONLY.
  194.     30 -     Key/userid revocation.  User can sign his own 
  195.         revocation to dissolve an association between a key
  196.         and a user ID, or certifier may revoke his previous 
  197.         certification of this key/userid pair. 
  198.         Material signed is public key pkt and User ID pkt.
  199.     40 -    Timestamping a signature certificate made by someone
  200.         else.  Can be used to apply trusted timestamp, and
  201.         log it in notary's log.  Signature of a signature.
  202.  
  203. When a signature is made to certify a key/UserID pair, it is computed
  204. across two packets-- the public key packet, and the separate User ID
  205. packet.  See below.  
  206.  
  207. The packet headers (CTB and length fields) for the public key packet
  208. and the user ID packet are both omitted from the signature
  209. calculation for a key certification.  
  210.  
  211. A key compromise certificate may be issued by someone to revoke his
  212. own key when his secret key is known to be compromised.  If that
  213. happens, a user would sign his own key compromise certificate with
  214. the very key that is being revoked.  A key revoked by its own
  215. signature means that this key should never be used or trusted again,
  216. in any form, associated with any user ID.  A key compromise
  217. certificate issued by the keyholder shall take precedence over any
  218. other key certifications made by anyone else for that key.  A key
  219. compromise signed by someone other than the key holder is invalid.  
  220.  
  221. Note that a key compromise certificate just includes the key packet
  222. in its signature calculation, because it kills the whole key without
  223. regard to any userid associations.  It isn't tied to any particular
  224. userid association.  It should be inserted after the key packet,
  225. before the first userid packet.  
  226.  
  227. When a key compromise certificate is submitted to PGP, PGP will place
  228. it on the public keyring.  A key compromise certificate is always
  229. accompanied in its travels by the public key and userIDs it affects.
  230. If the affected key is NOT already on the keyring, the compromise
  231. certificate (and its key and user ID) is merely added to the keyring
  232. anywhere.  If the affected key IS already on the keyring, the
  233. compromise certificate is inserted after the affected key packet. 
  234. This assumes that the actual key packet is identical to the one
  235. already on the key ring, so no duplicate key packet is needed.
  236. If a key has been revoked, PGP will not allow its use to encipher any
  237. messages, and if an incoming signature uses it, PGP will display a
  238. stern warning that this key has been revoked.
  239.  
  240. NOTE:  Key/userid revocation certificates WILL NOT BE SUPPORTED in
  241. this version of PGP.  But if we ever get around to supporting them,
  242. here are some ideas on how they should work...
  243.  
  244. A key/userid revocation certificate may be issued by someone to
  245. dissolve the association between his own key and a user ID.  He would
  246. sign it with the very key that is being revoked.  A key/userid
  247. revocation certificate issued by the keyholder shall take precedence
  248. over any other key certifications made by anyone else for that
  249. key/userid pair.  Also, a third party certifier may revoke his own
  250. previous certification of this key/userid pair by issuing a
  251. key/userid revocation certificate.  Such a revocation should not
  252. affect the certifications by other third parties for this same
  253. key/userid pair. 
  254.  
  255. When a key/userid revocation certificate is submitted to PGP, PGP
  256. will place it on the public keyring.  A key/userid revocation
  257. certificate is always accompanied in its travels by the public key it
  258. affects (the key packet and user ID packet precedes the revocation
  259. certificate).  If the affected key is NOT already on the keyring, the
  260. revocation certificate (and its key and user ID) is merely added to
  261. the keyring anywhere.  If the affected key IS already on the keyring,
  262. the revocation certificate is integrated in with the key's other
  263. certificates as though it were just another key certification.  This
  264. assumes that the actual key packet is identical to the one already on
  265. the key ring, so no duplicate key packet is needed.
  266.  
  267.  
  268.  
  269. Message digest "packet"
  270. -----------------------
  271.  
  272. The Message digest has no CTB packet framing.  It is stored
  273. packetless and naked, with padding, encrypted inside the MPI in the
  274. Signature packet.  
  275.  
  276. PGP versions 2.3 and later use a new format for encoding the message
  277. digest into the MPI in the signature packet, a format which is
  278. compatible with RFC1425 (formerly RFC1115).  This format is accepted
  279. but not written by version 2.2.  The older format used by versions 2.2
  280. and earlier is also accepted by version 2.3.
  281.  
  282. PGP versions 2.2 and earlier encode the MD into the MPI as follows:
  283.  
  284.         MSB             .   .   .                LSB
  285.  
  286.          0   1   MD(16 bytes)   0   FF(n bytes)   1
  287.  
  288. Enough bytes of FF padding are added to make the length of this
  289. whole string equal to the number of bytes in the modulus.
  290.  
  291. PGP versions 2.3 and later encode the MD into the MPI as follows:
  292.  
  293.         MSB               .   .   .                  LSB
  294.  
  295.          0   1   FF(n bytes)   0   ASN(18 bytes)   MD(16 bytes)
  296.  
  297. See RFC1423 for an explanation of the meaning of the ASN string.
  298. It is the following 18 byte long hex value:
  299.  
  300.         3020300c06082a864886f70d020505000410
  301.  
  302. Enough bytes of FF padding are added to make the length of this
  303. whole string equal to the number of bytes in the modulus.
  304.  
  305. All this mainly affects the rsa_private_encrypt() and rsa_public_decrypt()
  306. functions in rsaglue.c.
  307.  
  308. There is no checksum included.  We do include a copy of 2 bytes of the
  309. MD in the outer packet to help determine if we used the correct RSA
  310. key.
  311.  
  312.  
  313. Conventional Data Encryption Key (DEK) "packet"
  314. -----------------------------------------------
  315.  
  316. The DEK has no CTB packet framing.  The DEK is stored packetless and
  317. naked, with padding, encrypted inside the MPI in the RSA
  318. public-key-encrypted packet.
  319.  
  320. PGP versions 2.3 and later use a new format for encoding the message
  321. digest into the MPI in the signature packet.  (This format is not
  322. presently based on any RFCs due to the use of the IDEA encryption
  323. system.)  This format is accepted but not written by version 2.2.  The
  324. older format used by versions 2.2 and earlier is also accepted by
  325. version 2.3.
  326.  
  327. PGP versions 2.2 and earlier encode the MD into the MPI as follows:
  328.  
  329.         MSB                     .   .   .                          LSB
  330.  
  331.          0   1   DEK(16 bytes)   CSUM(2 bytes)   0   RND(n bytes)   2
  332.  
  333. CSUM refers to a 16-bit checksum appended to the high end of the DEK.
  334. RND is a string of NONZERO pseudorandom bytes, enough to make the length
  335. of this whole string equal to the number of bytes in the modulus.
  336.  
  337. PGP versions 2.3 and later encode the MD into the MPI as follows:
  338.  
  339.         MSB                     .   .   .                   LSB
  340.  
  341.          0   2   RND(n bytes)   0   1   DEK(16 bytes)   CSUM(2 bytes)
  342.  
  343. CSUM refers to a 16-bit checksum appended to the high end of the DEK.
  344. RND is a string of NONZERO pseudorandom bytes, enough to make the length
  345. of this whole string equal to the number of bytes in the modulus.
  346.  
  347. For both versions, the 16-bit checksum is computed on the rest of the
  348. bytes in the DEK key material, and does not include any other material
  349. in the calculation.  In the above MSB-first representation, the
  350. checksum is also stored MSB-first.  The checksum is there to help us
  351. determine if we used the right RSA secret key for decryption.
  352.  
  353.  
  354. All this mainly affects the rsa_public_encrypt() and rsa_private_decrypt()
  355. functions in rsaglue.c.
  356.  
  357.  
  358.  
  359. Conventional Key Encrypted data packet
  360. --------------------------------------
  361.  
  362. Offset  Length  Meaning
  363. 0       1       CTB for Conventional-Key-Encrypted data packet
  364. 1       4       32-bit (or maybe 16-bit) length of packet
  365. 5    ?    conventionally-encrypted data.
  366.         plaintext has 64 bits of random data prepended,
  367.         plus 16 bits prepended for "key check" purposes
  368.  
  369. The decrypted ciphertext may contain a compressed data packet or a
  370. literal plaintext packet.
  371.  
  372. After decrypting the conventionally-encrypted data, a special 8-byte
  373. random prefix and 2 "key check" bytes are revealed.  The random
  374. prefix and key check prefix are inserted before encryption and
  375. discarded after decryption.  This prefix group prefix is only visible
  376. only after decrypting the ciphertext in the packet.  
  377.  
  378. The random prefix serves to start off the cipher feedback chaining
  379. process with 64 bits of random material.  It may be discarded after
  380. decryption.  The first 8 bytes is the random prefix material, followed
  381. by the 2-byte "key-check" prefix.
  382.  
  383. The key-check prefix is composed of two identical copies of the last
  384. 2 random bytes in the random prefix, in the same order.  During
  385. decryption, the 9th and 10th bytes of decrypted plaintext are checked
  386. to see if they match the 7th and 8th bytes, respectively.  If these
  387. key-check bytes meet this criterion, then the conventional key is
  388. assumed to be correct.  
  389.  
  390.  
  391.  
  392. Compressed data packet
  393. ----------------------
  394.  
  395. Offset  Length  Meaning
  396. 0       1       CTB for Compressed data packet
  397. 1       4       32-bit (or maybe 16-bit) length of packet
  398. 5    1    Compression algorithm selector byte (1=ZIP)
  399. 6    ?    compressed data
  400.  
  401. The compressed data begins right after the algorithm selector byte.
  402. The compressed data may decompress into a raw literal plaintext data
  403. packet with its own CTB.
  404.  
  405.  
  406.  
  407. Literal data packet, with filename and mode
  408. -------------------------------------------
  409.  
  410. Offset  Length  Meaning
  411. 0       1       CTB for raw literal data packet
  412. 1       4       32-bit (or maybe 16-bit) length of packet
  413. 5    1    mode byte, 'b'= binary or 't'= canonical text
  414. 6    ?    filename, with leading string length byte
  415. ?    4    Timestamp of last-modified date, or 0, or right now
  416. ?    ?    raw literal plaintext data
  417.  
  418. The timestamp may be have to be derived in a system dependent manner.
  419. ANSI C functions should be used to get it if available, otherwise
  420. store the current time in it.  Or maybe store 0 if it's somehow not 
  421. applicable.
  422.  
  423. Whne calculating a signature on a literal packet, the signature
  424. calculation only includes the raw literal plaintext data that begins
  425. AFTER the header fields in the literal packet-- after the CTB, the 
  426. length, the mode byte, the filename, and the timestamp.  The reason
  427. for this is to guarantee that detached signatures are exactly the
  428. same as attached signatures prefixed to the message.  Detached
  429. signatures are calculated on a separate file that has no packet
  430. encapsulation.
  431.  
  432.  
  433.  
  434. Comment packet
  435. --------------
  436.  
  437. A comment packet is generally just skipped over by PGP, although it
  438. may be displayed to the user when processed.  It can be put in a
  439. keyring, or anywhere else.
  440.  
  441. Offset  Length  Meaning
  442. 0       1       CTB for Comment packet
  443. 1       1       8-bit length of packet
  444. 2       ?       ASCII comment, size is as in preceding length byte
  445.  
  446.  
  447.  
  448. Secret key certificate
  449. ----------------------
  450.  
  451. Offset  Length  Meaning
  452. 0       1       CTB for secret key certificate
  453. 1       2       16-bit (or maybe 8-bit) length of packet
  454. 3    1    Version byte (=2).  May affect rest of fields that follow.
  455. 4       4       Timestamp
  456. 8       2       Validity period, in number of DAYS (0 means forever)
  457. 10    1    Algorithm byte for RSA (=1 for RSA).  
  458.         --Algorithm byte affects field definitions that follow.
  459. ?       ?       MPI of RSA public modulus n
  460. ?       ?       MPI of RSA public encryption exponent e
  461.  
  462. ?    1    Algorithm byte for cipher that protects following 
  463.         secret components (0=unencrypted, 1=IDEA cipher)
  464. ?    8    Cipher Feedback IV for cipher that protects secret
  465.         components (not present if unencrypted)
  466. ?       ?       MPI of RSA secret decryption exponent d
  467. ?       ?       MPI of RSA secret factor p
  468. ?       ?       MPI of RSA secret factor q
  469. ?       ?       MPI of RSA secret multiplicative inverse u
  470.                 (All MPI's have bitcount prefixes)
  471. ?    2    16-bit checksum of all preceding secret component bytes
  472.  
  473. All secret fields in the secret key certificate may be password-
  474. encrypted, including the checksum.  The checksum is calculated from
  475. all of the bytes of the unenciphered secret components.  The public
  476. fields are not encrypted.  The encrypted fields are done in CFB mode,
  477. and the checksum is used to tell if the password was good.  The CFB
  478. IV field is just encrypted random data, assuming the "true" IV was
  479. zero.
  480.  
  481. NOTE:  The secret key packet does not contain a User ID field.  The 
  482. User ID is enclosed in a separate packet that always follows the secret 
  483. key packet on a keyring or in any other context.
  484.  
  485.  
  486. Public key certificate
  487. ----------------------
  488.  
  489. Offset  Length  Meaning
  490. 0       1       CTB for public key certificate
  491. 1       2       16-bit (or maybe 8-bit) length of packet
  492. 3    1    Version byte (=2).  May affect rest of fields that follow.
  493. 4       4       Timestamp of key creation
  494. 8       2       Validity period, in number of DAYS (0 means forever)
  495. 10    1    Algorithm byte for RSA (=1 for RSA).  
  496.         --Algorithm byte affects field definitions that follow.
  497. ?       ?       MPI of RSA public modulus n
  498. ?       ?       MPI of RSA public encryption exponent e
  499.                 (All MPI's have bitcount prefixes)
  500.  
  501. NOTE:  The public key packet does not contain a User ID field.  The 
  502. User ID is enclosed in a separate packet that always follows
  503. somewhere after the public key packet on a keyring or in any other
  504. context.  
  505.  
  506.  
  507.  
  508. User ID packet
  509. --------------
  510.  
  511. Offset  Length  Meaning
  512. 0       1       CTB for User ID packet
  513. 1       1       8-bit length of packet
  514. 2       ?       User ID string, size is as in preceding length byte
  515.  
  516. The User ID packet follows a public key on a public key ring.  It
  517. also follows a secret key on a secret key ring.
  518.  
  519. When a key is certified by a signature, the signature covers both the
  520. public key packet and the User ID packet.  The signature certificate
  521. thereby logically "binds" together the user ID with the key.  The
  522. user ID packet is always associated with the most recently occurring
  523. public key on the key ring, regardless of whether there are other
  524. packet types appearing between the public key packet and the
  525. associated user ID packet.
  526.  
  527. There may be more than one User ID packet after a public key packet.
  528. They all would be associated with the preceding public key packet.
  529.  
  530.  
  531. Keyring trust packet
  532. --------------------
  533.  
  534. The three different forms of this packet each come after: a public key
  535. packet, a user ID packet, or a signature packet on the public key
  536. ring.  They exist only on a public key ring, and are never extracted
  537. with a key.  Don't copy this separate trust byte packet from keyring,
  538. and do add it in back in when adding to keyring.
  539.  
  540. The meaning of the keyring trust packet is context sensitive.  The
  541. trust byte has three different definitions depending on whether it
  542. follows a key packet on the ring, or follows a user ID packet on the
  543. ring, or follows a signature on the ring.
  544.  
  545. Offset  Length  Meaning
  546. 0       1       CTB for Keyring trust packet
  547. 1       1       8-bit length of packet (always 1 for now)
  548. 2       1       Trust flag byte, with context-sensitive bit 
  549.                 definitions given below.
  550.  
  551.  
  552. For trust bytes that apply to the preceding key packet, the following
  553. bit definitions apply:
  554.  
  555.   Bits 0-2 - OWNERTRUST bits- Trust bits for this key owner.  Values are:
  556.        000 - undefined, or uninitialized trust.
  557.        001 - unknown, we don't know the owner of this key.
  558.        010 - We usually do not trust this key owner to sign other keys.
  559.        011 - reserved
  560.        100 - reserved
  561.        101 - We usually do trust this key owner to sign other keys.
  562.        110 - We always trust this key owner to sign other keys.
  563.        111 - This key is also present in the secret keyring.
  564.   Bits 3-5 - Reserved.
  565.   Bit 6 - VISITED bit- only used internally by the maintenance pass.
  566.   Bit 7 - BUCKSTOP bit- Means this key also appears in secret key ring.
  567.           Signifies the ultimately-trusted "keyring owner".
  568.           "The buck stops here".  This bit computed from looking 
  569.           at secret key ring.  If this bit is set, then all the
  570.           KEYLEGIT fields are set to maximum for all the user IDs for 
  571.           this key, and OWNERTRUST is also set to ultimate trust.
  572.  
  573. For trust bytes that apply to the preceding user ID packet, the
  574. following bit definitions apply:
  575.  
  576.   Bit 0-1 - KEYLEGIT bits- Validity bits for this key.
  577.           Set if we believe the preceding key is legitimately owned by 
  578.           who it appears to belong to, specified by the preceding user 
  579.           ID.  Computed from various signature trust packets that 
  580.           follow.  Also, always fully set if BUCKSTOP is set.  
  581.           To define the KEYLEGIT byte does not require that 
  582.           OWNERTRUST be nonzero, but OWNERTRUST nonzero does require 
  583.           that KEYLEGIT be fully set to maximum trust.
  584.        00 - unknown, undefined, or uninitialized trust.
  585.        01 - We do not trust this key's ownership.
  586.        10 - We have marginal confidence of this key's ownership.
  587.             Totally useless for certifying other keys, but may be useful 
  588.             for checking message signatures with an advisory warning 
  589.             to the user.
  590.        11 - We completely trust this key's ownership.
  591.         This requires either:
  592.         - 1 ultimately trusted signature (a signature from
  593.           yourself, SIGTRUST=111)
  594.         - COMPLETES_NEEDED completely trusted signatures
  595.           (SIGTRUST=110)
  596.         - MARGINALS_NEEDED marginally trusted signatures
  597.           (SIGTRUST=101)
  598.         COMPLETES_NEEDED and MARGINALS_NEEDED are configurable
  599.         constants.
  600.   Bit 7 - WARNONLY bit- If the user wants to use a not fully validated
  601.       key for encryption, he is asked if he really wants to use this
  602.       key.  If the user answers 'yes', the WARNONLY bit gets set,
  603.       and the next time he uses this key, only a warning will be
  604.       printed. This bit gets cleared during the maintenance pass.
  605.  
  606. For a trust byte that applies to the preceding signature, the
  607. following bit definitions apply:
  608.  
  609.   Bits 0-2 - SIGTRUST bits- Trust bits for this signature.  Value is
  610.              copied directly from OWNERTRUST bits of signer:
  611.        000 - undefined, or uninitialized trust.
  612.        001 - unknown
  613.        010 - We do not trust this signature.
  614.        011 - reserved
  615.        100 - reserved
  616.        101 - We reasonably trust this signature.
  617.        110 - We completely trust this signature.
  618.        111 - ultimately trusted signature (from the owner of the ring)
  619.   Bits 3-6 - Reserved.
  620.   Bit 7 - CONTIG bit- Means this signature leads up a contiguous trusted 
  621.           certification path all the way back to the ultimately-
  622.           trusted keyring owner, where the buck stops.  This bit derived 
  623.           from other trust packets.  
  624.  
  625. Note that the other kinds of trust bytes are mainly derived from the
  626. OWNERTRUST bits.  They are also derived from the BUCKSTOP bit (which
  627. will be set after creating a key, or after setting the owner trust to
  628. ultimate), and from the SIGTRUST bits, which is itself derived from a
  629. combination of OWNERTRUST bits and possibly the user's ratification.
  630.  
  631. When testing a key's integrity, we follow a trusted contiguous
  632. certification path back up to the owner of the key ring by following
  633. keyring trust bytes (for signatures) that have the CONTIG bits and
  634. SIGTRUST bits set, until we hit a keyring trust byte (for a key) that
  635. has BUCKSTOP bit set.  Then we know we've reached the top of the
  636. trust pyramid, the keyring owner.  Prior to this operation, we set
  637. all the CONTIG bits by navigating the pyramid from the top down, by
  638. testing the SIGTRUST bits that are "trustwise contiguous" with the
  639. top of the pyramid, in a special keyring maintenance pass.  
  640.  
  641. The key legitimacy is ultimately determined by a probablistic
  642. fault-tolerant method, as follows.  We also set KEYLEGIT if BUCKSTOP is
  643. set, which means that this is our own key.  The OWNERTRUST bits can only
  644. become defined (nonzero) if KEYLEGIT is fully set already.  At the
  645. moment KEYLEGIT becomes fully set (and not before), we ask the user to
  646. define the OWNERTRUST bits.
  647.  
  648. This probablistic fault-tolerant method of determining public key
  649. legitimacy is one of the principle strengths of PGP's key management
  650. architecture, as compared with PEM, for decentralized social
  651. environments.  
  652.  
  653. The trust of a key owner (OWNERTRUST) does not just reflect our
  654. estimation of their personal integrity, it also reflects how competent
  655. we think they are at understanding key management and using good
  656. judgement in signing keys.  The OWNERTRUST bits are not computed from
  657. anything -- it requires asking the user for his opinion.  
  658.  
  659. To define the OWNERTRUST bits for a key owner, ask:
  660.     Would you always trust "Oliver North" 
  661.     to certify other public keys?
  662.     (1=Yes, 2=No, 3=Usually, 4=I don't know) ? _
  663.  
  664. If a key is added to the key ring the trust bytes are initialized
  665. to zero (undefined).
  666.  
  667.  
  668. [--manual setting of SIGTRUST/OWNERTRUST not implemented]
  669. Normally, we derive the value of the SIGTRUST field by copying it
  670. directly from the signer key's OWNERTRUST field.  Under special
  671. circumstances, if the user explicitly requests it with a special PGP
  672. command, we may let the user override the copied value for SIGTRUST
  673. by displaying an advisory to him and asking him for ratification,
  674. like so:
  675.     This key is signed by "Oliver North",
  676.     whom you usually trust to sign keys.
  677.     Do you trust "Oliver North" 
  678.     to certify the key for "Daniel Ellsberg"?
  679.     (1=Yes, 2=No, 3=I don't know) ? _      <default is yes>
  680.  
  681. Or:
  682.     This key is signed by "Oliver North",
  683.     whom you usually do not trust to sign keys.
  684.     Do you trust "Oliver North" 
  685.     to certify the key for "Daniel Ellsberg"?
  686.     (1=Yes, 2=No, 3=I don't know) ? _      <default is no>
  687.  
  688. An "I don't know" response to this question would have the same
  689. effect as a response of "no".
  690.  
  691. If we had no information about the trustworthyness of the signer (the
  692. OWNERTRUST field was uninitialized), we would leave the advisory note
  693. off.  
  694.  
  695.  
  696. Certifying a public key is a serious matter, essentially promising to
  697. the world that you vouch for this key's ownership.  But sometimes I
  698. just want to make a "working assumption" of trust for someone's
  699. public key, for my own purposes on my own keyring, without taking the
  700. serious step of actually certifying it for the rest of the world.  In
  701. that case, we can use a special PGP keyring management command to
  702. manually set the KEYLEGIT field, without relying on it being computed
  703. during a maintenance pass.  Later, if a maintenance pass discovers a
  704. KEYLEGIT bit set that would not have been otherwise computed as set
  705. by the maintenance pass logic, it alerts me and asks me to confirm 
  706. that I really want it set.
  707. [--end of not implemented section]
  708.  
  709.  
  710. During routine use of the public keyring, we don't actually check the
  711. associated signatures certifying a public key.  Rather, we always 
  712. rely on trust bytes to tell us whether to trust the key in question. 
  713. We depend on a separate maintenance pass to actually check the key
  714. signature certificates against the associated keys, and to set the
  715. trust bytes accordingly.
  716.  
  717.  
  718. The maintenance pass operates in a top-of-pyramid-down manner as
  719. follows.
  720.  
  721. If at any time during any of these steps the KEYLEGIT field goes from
  722. not fully set to fully set, and the OWNERTRUST bits are still undefined,
  723. the user is asked a question to define the OWNERTRUST bits.  First, for
  724. all keys with BUCKSTOP set, check if they are really present in the
  725. secret keyring, if not, the BUCKSTOP bit is cleared.  SIGTRUST and
  726. KEYLEGIT is initialized to zero for non-buckstop keys.
  727.  
  728. The real maintenance pass is done in a recursive scan:  Start with
  729. BUCKSTOP keys, find all userid/key pairs signed by a key and update
  730. the trust value of these signatures by copying the OWNERTRUST of the
  731. signer to the SIGTRUST of the signature.  If this makes a key fully
  732. validated, start looking for signatures made by this key, and update
  733. the trust value for them.
  734.  
  735. If a signature fails to verify, obnoxiously alert the user, drop it from
  736. the key ring, and then do the maintenance pass to calculate all the
  737. ring-wide cascaded effects from this, if any.  A failed signature should
  738. be exceedingly rare, and it may not even result in a KEYLEGIT field
  739. being downgraded.  Having several signatures certifying each key should
  740. prevent damage from spreading too far from a failed certificate.  But if
  741. dominoes do keep falling from this, it may indicate the discovery of an
  742. important elaborate attack.
  743.  
  744.  
  745.  
  746. Public Key Ring Overall Structure
  747. =================================
  748.  
  749. A public key ring is comprised of a series of public key packets,
  750. keyring trust packets, user ID packets, and signature certificates.
  751.  
  752. Here is an example of an ordered collection of packets on a ring:
  753.  
  754. --------------------------------------------------------------------
  755.   Public key packet
  756.       Keyring trust packet for preceding key
  757.       User ID packet for preceding key
  758.           Keyring trust packet for preceding user ID/key association
  759.       Comment packet
  760.           Signature certificate to bind preceding User ID and key pkt
  761.           Keyring trust packet for preceding signature certificate
  762.           Signature certificate to bind preceding User ID and key pkt
  763.           Keyring trust packet for preceding signature certificate
  764.           Signature certificate to bind preceding User ID and key pkt
  765.           Keyring trust packet for preceding signature certificate
  766.  
  767.   Public key packet
  768.       Keyring trust packet for preceding key
  769.       User ID packet for preceding key
  770.           Keyring trust packet for preceding user ID/key association
  771.           Signature certificate to bind preceding User ID and key pkt
  772.           Keyring trust packet for preceding signature certificate
  773.       User ID packet for preceding key
  774.           Keyring trust packet for preceding user ID/key association
  775.       Comment packet
  776.           Signature certificate to bind preceding User ID and key pkt
  777.           Keyring trust packet for preceding signature certificate
  778.           Signature certificate to bind preceding User ID and key pkt
  779.           Keyring trust packet for preceding signature certificate
  780.  
  781.   Public key packet
  782.       Keyring trust packet for preceding key
  783.       Compromise certificate for preceding key
  784.       User ID packet for preceding key
  785.           Keyring trust packet for preceding user ID/key association
  786.           Signature certificate to bind preceding User ID and key pkt
  787.           Keyring trust packet for preceding signature certificate
  788. --------------------------------------------------------------------
  789.